Hyper Stacks 1994 May/Hyper Stacks (Pacific HiTech)(1994)[Mac].iso/Utilities/HC 21 Tech Notes

Internet Message Format | 1991-09-25 | 24KB

From: [e-mail]
Date: Fri, 28 Jun 91 11:39:57 CDT
Subject: HyperCard 2.1 Release Notes (AppleEvents)

>  ... I see 'File Sharing Extension' and 'Finder' as two programs
>  apparently supporting events.  Where can I get docs on sending
>  them events?

I don't know about File Sharing Extension.  I do know about the Finder --
the suite of Apple events that the 7.0 Finder understands will be
published in the Apple Event Registry, a version of which will shortly
be available from the Apple Programmers' and Developers' Association
(APDA).  However, you'll need an XCMD to send these events to the
Finder from HyperCard 2.1.

>  Can you give me a HyperTalk string that will send an event to the
>  Finder on another (7.0 w/linking) Mac that will tell it to launch
>  HyperCard?  If I can get HC running then I can use it to launch
>  other Apps and such, but I'm guessing I should be able to tell the
>  finder to oapp HyperCard?

Unfortunately, the Finder does not accept standard open events from
remote machines -- I believe that this decision was made by the 7.0
team to make the whole program linking scheme more secure from
viruses.  Therefore there is no way at present to launch an app on
a remote machine from HyperCard, unless HyperCard or some other
app that can sublaunch things is running on that machine.  I can
only recommend two things:

  - Put HyperCard in the Startup Items folder in the System Folder.
    This will make it launch automatically when the machine boots.

  - Find or write a nice small utility app that can accept some
    of the standard Apple events from remote machines and put it
    in the Startup Items folder.

Here, as promised, are the articles I posted to comp.sys.mac.hypercard.

-----


HyperCard 2.1 Release Notes


Overview of this Release
------------------------

HyperCard 2.1 is the version of HyperCard recommended for use with System
7.0. It is also compatible with System 6.0.5 and System 6.0.7.


Revisions for Support of System 7.0 Features
--------------------------------------------

These revisions are grouped by their associated Toolbox Manager.


Alias Manager

    When the Alias Manager is present, HyperCard 2.1 will call it to
resolve alias files.  Therefore, the following commands will work properly
with alias files.

    go to stack <alias file>
    open <alias file> with <alias file>
    open file <alias file>
    write to file <alias file>
    read from file <alias file>
    picture <alias file>

    The XCMD callback GetFilePath will also resolve alias files.
Therefore, XCMDs that use this callback to locate files will require no
revision to work with alias files.  (The Picture XCMD is an example.)

    In addition, if HyperCard finds an alias file when looking for the Home
stack on startup, the alias file will be resolved.


Apple Event Manager

    When the AppleEvent Manager is present, HyperCard 2.1 will use it to
process and send Apple events.  HyperCard will recognize and handle the
standard Apple events for opening documents, printing documents, quitting,
executing a script, and evaluating an expression.

    In addition, several of HyperTalk's built-in commands will have the
added ability to send specific Apple events to other applications.

    Event class  Event ID       Related HyperTalk command
    -----------  --------       -------------------------
    'aevt'       'oapp'         open <application>
    'aevt'       'odoc'         open <document> with <application>
    'aevt'       'pdoc'         print <document> with <application>
    'aevt'       'quit'         close <application>
    'aevt'       'clos'         close <document> with <application>
    'misc'       'dosc'         send <expr> to program <programExpr>
    'misc'       'eval'         request <expr> of program <programExpr>

    If you want to launch another application or open a document with
another application, use the HyperTalk command "open".  If you want to
print a document with another application, use the command "print".  If you
want to close a document in another application or quit another
application, use the command "close".  If you want to execute a script or
macro in another application, use the HyperTalk command "send".  If you
want to evaluate an expression in another application, use the command
"request".

    Please note that among these Apple events, only 'oapp', 'odoc', 'pdoc',
and 'quit' are universally supported.  All other Apple events that
HyperCard can send will be effective only if the target application
includes specific support for them. For example,

    close "My Expense Report" with "FabCalc"

will work properly only if the application FabCalc supports the 'clos'
Apple event.

    The "open", "print", and "close" commands will work only with
applications that reside on the same machine as HyperCard.  The "send" and
"request" commands will work with any linkable program running on the
network. See "Determining the Target Program", below.

Sending scripts to other programs

    The send command in HyperTalk will send a "do script" Apple event from
HyperCard to another application running remotely.  It can be used to send
a script to any program that understands the standard 'dosc' Apple event.
By default, HyperCard waits for a reply from the target program before
continuing. However, you can specify that you don't want to wait for a
reply.

    Examples:

    send "make waves" to program "De Anza 6/2nd:WildCraft:HyperCard"
    send "build {project}" to program "MPW Shell" without reply

Evaluating expressions in other programs

    The request command in HyperTalk will send an "evaluate expression"
Apple event from HyperCard to another application running remotely.  It can
be used to send an expression to any program that understands the standard
'eval' Apple event.  The value of the expression will be put into the local
variable "it".

    Examples:

    request "the name of this stack" of program "HyperCard"
    request "{target}" from program "MPW Shell"

Handling failures

    The "send", "open", "print", "close", and "request" commands set "the
result" as follows when they fail.

Condition                               the result
---------                               ---------------
User canceled the "Link to program"     "Cancel"
  dialog.
Target program didn't handle event.     "Not handled by target program"
Target program timed out.               "Timeout"
Target program returned error string    the string
  in reply.
Target program returned error number    "Got error <errorNum>
  in reply, or AESend returned some       when sending Apple( event"
  other error.

Establishing program links

    When sending Apple events to another program, if HyperCard has not
established a link with the target program, the user will be presented with
a dialog, through which the link will be established.  If a link has
already been established between HyperCard and the target program, the
Apple event will be sent without further user interaction.

Determining the target program

    The target program for Apple events is specified by a string in the
following format:

    zone:machine:program

    Examples:

    "Fifth Floor:Gizmo:MacWrite"
    "Baby mac:MacWrite"
        -- zone omitted; HyperCard assumes same zone
    MacWrite
        -- zone and machine omitted; HyperCard assumes same zone,
            same machine

    HyperCard's address on the network is contained in the property, "the
address".

    You can use the itemDelimiter property to parse program addresses.
For example, given a string that specifies a target program, the following
HyperTalk function will return the name of the program if you send it a
colon as the delimiter and the string as the text.

    function lastHCItem delim,theText
      put the itemDelimiter into savedDelimiter
      set the itemDelimiter to delim
      put the last item of theText into lastItem
      set the itemDelimiter to savedDelimiter
      return lastItem
    end lastHCItem

Choosing a target program

    The answer command has been extended for use with the Program Linking
dialog, so that scripters can allow users to select a program to link to.

    answer program prompt { of type <factorList> }

When used in this way, the answer command displays the PPC browser, from
which the user can select any program running on any machine connected to
the AppleTalk network.  A string representing the program the user selects
is placed into the local variable "it".

Examples:

    answer program "Where did you say that program was again?"
    answer program "Choose a spelling checker:" of type "Spellcheck"

    In addition,  a scripter can determine which programs are running on
the same machine as HyperCard by examining the new HyperTalk function, "the
programs".  It returns a return-delimited list of all the linkable programs
currently running on the same machine as HyperCard.

Handling Apple events

    When HyperCard receives an Apple event, it will send a new HyperTalk
system message, "appleEvent", to the current card, along with parameters
that enable a script to determine the class, id, and the sender of the
Apple event.  For example, when the Finder sends HyperCard an Apple event
of class 'aevt' and id 'odoc', HyperCard sends the HyperTalk message
"appleEvent aevt,odoc,Finder" to the current card.

    A script that handles an appleEvent message can gather the parameters
of the Apple event by using the new HyperTalk command "request".

    request appleEvent data { [ of | with ] keyword <expr> }

This command puts the parameter or attribute with the specified keyword
into the local variable "it".  For example, you can obtain a parameter of
keyword "errs", the standard Apple event keyword for an error string, as
follows:

    request appleEvent data with keyword "errs"
    put it into errorString

If there is no attribute or parameter with the keyword you specify,
HyperCard sets the result to "Not found".

    If you don't supply a keyword, HyperCard assumes you're requesting the
direct object of the Apple event, which is defined by the Apple event
manager as the parameter with keyword "----".  The request command also
supports several special cases for important attributes of Apple events:

    request appleEvent class
    request appleEvent id
    request appleEvent sender
    request appleEvent return id

    HyperCard will attempt to convert all the Apple event parameters to
strings, for use in HyperTalk.  The Apple event manager automatically
handles the conversion of numerical forms to strings; HyperCard installs
coercion handlers for alias records, return ids, process serial numbers,
target ids, class and id types, and lists.

    If an incoming Apple event specifies that user action is not
permissible, the global property lockErrorDialogs will automatically be set
to TRUE (see "Error Handling", below).  The scripter can override this
setting.

    Example:  a scripter defines an event of class 'WILD' and id 'cnvt' as
a request to convert a 1.2.5 stack to the 2.0 file format.  The direct
object of the Apple event is defined to be the pathname of the stack.  The
following script will do the trick.

    on appleEvent eventClass,eventID,sender
      if eventClass & eventID is not "WILDcnvt"
      then pass appleEvent
      else
        request appleEvent data
        if it is empty then exit appleEvent
        go to stack it
        if the result is not empty then exit appleEvent

        if there is a menuItem "Convert Stack..." in menu "File"
        then doMenu "Convert Stack..." without dialog
      end if
    end appleEvent

    Example:  when a stack is opened from the Finder while HyperCard is
running, HyperCard 2.1 will open the stack in a new window.  This behavior
is different from previous versions of HyperCard, which would go to the
stack in the currently active window.  If you prefer the old behavior, you
can put the following script in your Home stack.

    on appleEvent eventClass,eventID,sender
      if eventClass & eventID is not "aevtodoc"
      then pass appleEvent
      else
        request appleEvent data
        put line 1 of it into stackToOpen
        go to stack stackToOpen
      end if
    end appleEvent

    If HyperCard receives the appleEvent message, either because it was not
intercepted by a script or because it was passed to it by a script,
HyperCard will check whether the current Apple event is of the types it
knows how to respond to, and if so, will treat it appropriately.  HyperCard
2.1 will recognize the following standard Apple events: 'odoc', 'pdoc',
'quit', 'dosc', and 'eval'.

    HyperCard responds to the 'odoc' event by checking whether the
specified files are stacks and, if so, opening them, each in a new window.

    HyperCard responds to the 'pdoc' event by checking whether the
specified files are stacks and, if so, opening them one at a time in a new
window, printing them, and closing them again.

    HyperCard responds to the 'quit' event just as it would if "Quit
HyperCard" were chosen from the File menu.

    HyperCard responds to a 'dosc' event by compiling and executing the
HyperTalk statements sent to it as the direct object of the event.

    HyperCard responds to an 'eval' event by evaluating the expression sent
to it as the direct object of the event and putting the value into the
direct object of the reply.

Replying to Apple events

    Scripters can reply to Apple events from HyperTalk with a new command,
"reply".

    reply <expr> { with keyword <expr> }

If you don't specify a keyword for the reply parameter, the parameter will
become the direct parameter of the reply.  If you wish to return an error
string, you can use the following form of the reply command:

    reply error <expr>

This is equivalent to:

    reply <expr> with keyword "errs"

    The reply event is sent when the chain of execution is complete.

    For example, the following script will handle Apple events of class
'WILD' and type 'defn' by searching for a string in a background field
named "Glossary Entry" and returning the contents of a background field
named "Definition".

    on appleEvent eventClass,eventID,sender
      if eventClass is "WILD" and eventID is "defn" then
        request appleEvent data
        find it in field "Glossary Entry"
        if the result is empty  -- successful find
        then reply field "Definition"
        else reply error "Not found"
      else pass appleEvent
    end appleEvent

The "request" and "reply" commands set the result to "No current Apple(
event." when there is no current Apple event to handle.


Miscellaneous Revisions
-----------------------

Menus

    When you ask for the names of the Apple, Help, and Application menus
>From HyperTalk, you get "Apple", "System Help", and "Application",
respectively.

Error Handling

    In order to execute scripts without interaction with the user, as well
as to provide a better means for testing HyperCard's error messages, it's
now possible to lock error dialogs and to put HyperTalk into a "quiet
mode" for script execution.  When HyperTalk encounters an error while in
"quiet mode", it aborts execution of pending scripts just as it normally
would, but instead of displaying a dialog with an error message, it sends a
"errorDialog" message to the current card with the error message as its
parameter.  This message substitutes for the first "idle" message that
would be sent in normal mode after HyperTalk cleans up and HyperCard
returns to its main event loop.

    Example:

    set lockErrorDialogs to TRUE  -- puts HyperTalk into "quiet mode"
    lock error dialogs  -- an alternate form
    unlock error dialogs

When HyperCard receives an Apple event for which the sender has specified
that no user interaction is allowed, it will automatically set
lockErrorDialogs to TRUE before handling the event.

Determining which version of System Software is running

    A new function has been added to HyperTalk, "the systemVersion".  It
returns the version of system software is running in a decimal string.  For
example, it will return 6.07 instead of 6.0.7, to allow scripters to use it
with HyperTalk's arithmetic operators.

Specifying Windows

    You can now refer to windows by number and by id as well as by name.
Therefore, the following commands are now valid.

    get the id of the card window
    set the loc of window 1 to 50,50
    hide last window

    Both the Picture and Palette XCMDs now send the id of a newly created
window as an additional parameter to its open message.  For example, after
the Picture XCMD creates a new window, it sends the following message to
the current card:

    openPicture <name of window>,<id of window>

Read and Write

    The HyperTalk "read" and "write" commands have been enhanced.  The
following examples are now valid.

    read from file "Fred" at 100 for 12
    read from file "Fred" until end  -- 'eof' works too
    write myVar to file "Fred" at 200
    write moreStuff to file "Fred" at end  -- 'eof' works too

In addition, the 16K limit on the amount of text that could be read at once
has been removed.  If the amount of text you ask for won't fit in memory,
HyperCard sets the result to "Not enough memory to read from file."

Getting the internal modem for the Portable to work with "dial"

    A new global property, "the dialingTime", has been added, especially
for users of the internal modem for the Macintosh Portable.  It determines
how long HyperCard waits, in ticks, after sending the dial string, before
closing the serial connection with the modem.   The default is 180 (3
seconds).

Owners

    Windows and cards now have an "owner" property.  For windows, the owner
is determined as follows.

    Creator                   Owner
    ----------                ----------
    HyperCard                 "HyperCard"
    desk accessory or driver  "System"
    XCMD                      the name of the XCMD
    anything else             "Unknown"

    The owner of a card is the name of its background.

More Parameters Available

    The parameters for the "start", "stop", and "set" commands are now
available within overriding handlers.


Summary
-------

    New messages:  appleEvent, errorDialog
    New commands:  request, reply
    New functions:  programs(), systemVersion()
    New properties:  the address, the itemDelimiter, the lockErrorDialogs,
the dialingTime, the owner
    New constants:  comma, colon

    Enhanced commands: open, print, close, send, read, write, answer, lock,
unlock, set, start, stop


-----


When HyperCard 2.1 receives an Apple event, it sends an appleEvent
message to the current card.  That means that you can respond to Apple
events with HyperTalk scripts.  But before you try to write such scripts,
there are some terms and conventions you should be familiar with.

The figure
----------

Apple events are like a package full of raw materials that arrive at a
factory.  They have a return address on them -- in HyperTalk, a string of
the form "Zone:Macintosh:Program".  They have an explanation of what their
contents are for -- the class and id, which together consititute a verb,
directing the receiver what do to with the package.  And of course there
are the contents themselves -- the event parameters.

When you get one of these packages, you have to unpack it before you can
make something out of the raw materials inside.  But you can't just rip
into the package willy-nilly.  You have to ask for what you want, by name.
"Give me the snod." "OK, now give me the lerd."  You unpack the contents,
one by one, and make out of them whatever you're directed to make by the
class and id.

The catch is that the package doesn't come with a packing list.  You're
supposed to know what's in it -- you have a big book that tells you that
whenever you get a package that you're supposed to make into a "wild plum",
it's supposed to have a "bork", a "flam", and a "nitz" inside of it.  So
you unpack the bork, the flam, and the nitz, and then you make the wild
plum out of them and send it back.

    Apple event = package
    class and id = terse directions for what to do with the package
    parameters = contents of the package
    keywords = names for each thing in the package


The lesson
----------

In HyperTalk, when you handle the appleEvent message, you first look at
the class and id, and they tell you what you're supposed to do with the
event.  If it's an event that you know how to handle, you already know what
the parameters are -- you've agreed with the sender in advance on what's
supposed to be in it, or it's a standard Apple event defined in the
voluminous standard documentation.  So you unpack the parameters with the
"request" command, manipulate them, and send back what you made out of them
with the "reply" command.

The script might look like this:

   on appleEvent class,id,sender
     if class & id is "wildplum" then
       request ae data with keyword "bork"
       if the result is not empty then   -- probably "Not found"
         reply error "Expected a bork but got none."
         exit appleEvent
       end if
       put it into theBork
       request ae data with keyword "flam"
       .
       .
       .
       .
       get wildPlumMakingFunction(theBork,theFlam,theNitz)  -- process it
       reply it  -- send back the reply
     else pass appleEvent  -- we don't recognize this event; pass it on
   end appleEvent


Keywords
--------

Think of a keyword for a piece of data in the package as its name -- it's
the handle you need to pull it out of the package.  Asking for a parameter
by keyword is the same as asking for a piece of raw material by name.

Keywords are arbitrary.  Whoever invents an Apple event makes them up, on
the spot, out of the blue, to name the pieces of data that go along with
the event.  The standard Apple events that have already been defined, along
with the keywords for their required and optional parameters, are described
in the Apple Event Registry.


The direct object
-----------------

Many Apple events arrive with just one piece of raw material in them, or
one piece that's more important than the others.  By convention, this piece
is given the keyword "----" and is referred to in the Apple event
documenation as "the direct object" or "the direct parameter".  These are
pretty ugly names, so in HyperTalk you can just call it the "data" and
leave off the keyword specification -- HyperCard will know what you're
talking about.

   request appleEvent data

This is equivalent to the following statement.

   request appleEvent data of keyword "----"

The direct object for the 'odoc' event is the list of documents to open.
The direct object for the 'dosc' event is the script to execute.  And so
on.


Event attributes
----------------

Apple events come along with more than just an address, a verb, and pieces
of data.  They also come with modifiers, or "attributes", which you can
think of as "special handling instructions".  The class, id, and sender are
all attributes also, but HyperCard gives you these automatically as
parameters to the appleEvent message.  The timeout value, the transaction
id, and the return id -- the identifier you put on the reply so that the
sender knows, when his wild plum arrives, which package you made it out of
-- are additional attributes.  If you need to look at these, the "request"
command will let you.

You can get the return id,

   request appleEvent return id
   request appleEvent data of keyword "rtid"  -- same thing, only uglier

the timeout value,

   request appleEvent data of keyword "timo"

the transaction id,

   request appleEvent data of keyword "tran"

and whatever else you think you need, as long as you know its keyword.  We
have special forms of the request command for the class, id, sender, direct
object, and return id -- for everything else, you have to tell HyperCard
what you want by keyword.

   request appleEvent class   -- gives you the class attribute
   request appleEvent id      -- gives you the id attribute
   request appleEvent sender  -- gives you the sender attribute
   request appleEvent data    -- gives you the direct object parameter
   request appleEvent return id   -- gives you the return id attribute